package org.example.azapi;
import org.example.azapi.constants.*;
/**
 * AzAttributeValue is the parent interface of all the subinterfaces
 * that provide for the implementation of each XACML DataType as
 * enumerated by the enums that implement {@link AzDataTypeId}. 
 * <p>
 * Subinterfaces of AzAttributeValue are implemented to meet the requirements
 * of each individual XACML DataType.
 * <p>
 * The basic design is that a Java object, which can handle the
 * requirements of the AzDataType be used for setValue(T). For
 * example, in the case of XACML #anyURI, the Java URI type is
 * used to meet those requirements.
 * <br>
 * In some cases there will be an obvious one to one mapping between 
 * the XACML DataType identified by an AzDataType and a Java type 
 * that meets the XACML DataType requirements. 
 * <br>
 * In other cases there may be more complexity than a single available 
 * Java class required to meet the requirements specified by the XACML 
 * DataType. In those cases, custom interfaces may be implemented to 
 * meet the requirements, as exampled by the AzData* interfaces that
 * are used for some interfaces.
 * <p>
 * Subclasses of AzAttributeValue are "type-safe" in the sense that they
 * define corresponding AzDataType and AzAttributeValueType members which
 * ensure that only the specific XACML DataType identifier (AzDataType)
 * that corresponds to the AzAttributeValueType<DataType> subinterface are
 * kept together in a an AzAttributeValue<DataType> subinterface of this
 * class.
 * <p>
 * Note: the Sun XACML Implementation:
 * <pre>
 *    http://sunxacml.sourceforge.net/javadoc/index.html
 * </pre>
 * was used as the basis for defining the characteristics of many of 
 * these datatypes, esp wrt to dates, times, durations, byte[], etc. 
 * <br>
 * Note: it is an objective of the AzAPI to be able to "wrap" the   
 * Sun XACML Client Implementation for the purpose of serializing
 * xml calls to the Sun XACML PDP. Note also in this regard that the
 * AzAPI is intended to be XACML 2.0 compliant, while the Sun 
 * Implementation is a pre-XACML 2.0 implementation and lacks several
 * XACML 2.0 features. i.e. the AzAPI is intended to be "downward
 * compatible" to subset implementations.
 * 
 * @author Rich
 *
 */
public interface AzAttributeValue<U extends Enum<U> & AzDataTypeId, V> {

	/**
	 * Set the XACML DataType that this AzAttributeValue will contain.
	 * @param d
	 */
	//public void setType(AzDataType d);
	
	/**
	 * Return the XACML DataType of this attribute
	 * 
	 * @return azDataType
	 */
	public U getType();
	
	/**
	 * Set the AzAttributeValueType, which contains an actual instance
	 * of a value for this attribute. The subclass implementations of
	 * the AzAttributeValueType will constrain the value data to
	 * conform with the requirements of the AzDataType.
	 * value 
	 * TBD: should this member be immutable?
	 * @param azVal
	 */
	public void setValue(V azVal);
	
	/**
	 * Return the value in the Java object used to represent the
	 * XACML DataType. This object will contain the value from
	 * which the XACML value is derived, but it is not necessarily
	 * the format necessary for XACML. The XACML value is obtained
	 * from the toXacmlString() method.
	 * 
	 * @return value
	 */
	public V getValue();
	
	/**
	 * Return a String which can be used in an XML representation
	 * of the XACML Request.
	 * @return the XACML String representation of the attribute's value
	 */
	public String toXacmlString();
	
	/**
	 * Validate the value stored in this AzAttributeValue instance
	 * against any internally specified constraints.
	 * <b>
	 * Subtype interfaces should override this method as it will 
	 * in general be implemented distinctively for each XACML
	 * DataType.
	 * <b>
	 * Default return value is true, if validate() not implemented.
	 * 
	 * @return true if valid; false if constraint violated
	 */
	public boolean validate();
}
